package edu.mercer.sse.util;

import java.util.Map;
import java.util.Set;
import java.util.concurrent.Callable;
import java.util.concurrent.Future;

/**
 * Application encapsulated by Wrapper Facade.<p>
 * 
 * Configuration specifies applications available and their information.<p>
 * 
 * A Generic - application wrapper; i.e., 'Validation'
 * 
 * @see Configuration
 */

public interface Utility<A> extends Callable<Future<ExecutionResults>>
{
	/**
	 * Retrieve all utility applications' names.<p>
	 * 
	 * Key used to refer to each utility defined in Configuration.<p> 
	 * 
	 * @return  &#60;String&#62; containing key of each application defined in 
	 * 	Configuration
	 * 
	 * @see Configuration
	 */
	
	Set<String> getUtilities(); 

	
	/**
	 * Retrieve any parameter names.<p>
	 * 
	 * As defined for this utility in Configuration.<p>
	 * 
	 * Examples: FILE_IN, FILE_OUT, PDF_COMPRESSION as in:<p>
	 * 
	 * /usr/bin/tiff2pdf -j -q {PDF_COMPRESSION} -f -o {FILE_OUT} {FILE_IN}<p>
	 * 
	 * @return  &#60;String&#62; containing key of each parameter
	 */
	
	Set<String> getParameterNames();
	
	
	/**
	 * Supply parameter value.<p>
	 * 
	 * As defined for this utility in Configuration.<p>
	 * 
	 * Examples: FILE_IN, FILE_OUT, PDF_COMPRESSION as in:<p>
	 * 
	 * /usr/bin/tiff2pdf -j -q {PDF_COMPRESSION} -f -o {FILE_OUT} {FILE_IN}<p>
	 * 
	 * Set 'PDF_COMPRESSION' value to '85', result:
	 * 
	 * /usr/bin/tiff2pdf -j -q 85 -f -o {FILE_OUT} {FILE_IN}<p>
	 * 
	 * @param value - String containing value supplied to utility application 
	 * 	for given key
	 * 
	 * @return  this
	 */
	
	Utility<A> setParameterValue( final String key, final String value );


	/**
	 * Retrieve parameter value.<p>
	 * 
	 * As defined for this utility in Configuration.<p>
	 * 
	 * Examples: FILE_IN, FILE_OUT, PDF_COMPRESSION as in:<p>
	 * 
	 * /usr/bin/tiff2pdf -j -q {PDF_COMPRESSION} -f -o {FILE_OUT} {FILE_IN}<p>
	 * 
	 * setParameterValue(PDF_COMPRESSION, 85) is called:<p>
	 * 
	 * /usr/bin/tiff2pdf -j -q 85 -f -o {FILE_OUT} {FILE_IN}<p>
	 *
	 * Get 'PDF_COMPRESSION' value now yields '85'.
	 * 
	 * @param value - String containing value supplied to utility application 
	 * 	for given key
	 * 
	 * @return  this
	 */
	
	String getParameterValue();
	
	
	/**
	 * Supply multiple parameter values.<p>
	 * 
	 * @param values - Map&#60;String,String&#62; containing names and values 
	 * 	for parameter argument substitution
	 * 
	 * @return  this
	 */
	
	Utility<A> setParameterValues( final Map<String,String> values );
	
	
	/**
	 * Retrieve Map of multiple parameter names and values.<p>
	 * 
	 * @return Map&#60;String,String&#62; containing names and values for 
	 * 	parameter argument substitution
	 */
	
	Map<String,String> getParameterValues();
	
	
	/**
	 * Execute application encapsulated by this.<p>
	 * 
	 * Provides Future containing ExecutionResults.<p>
	 * 
	 * @return  Future&#60;ExecutionResults&#62; for utility execution
	 * 
	 * @throws E - Throwable
	 * 
	 * @see ExecutionResults
	 * 
	 * @see Future
	 */
	
	Future<ExecutionResults> call();	


}//interface
